/**
 * @(#)UsuariosSeguridadManager.java Nov 10, 2006
 *
 * Copyright (c) 2005-2010 Psiqueware S.A. de C.V. All Rights Reserved.
 * This software is the proprietary information Psiqueware S.A. de C.V.
 * Use is subject to license terms.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR
 * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
 * FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER
 * IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
 * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 *
 *
 * <br/>Usuario : AngelElectrico
 * <br/>Creaci&oacute;n: Nov 10, 2006 - 3:49:34 PM
 * <br/>
 * <br/>
 * <br/><t5>Cambios :</t5>
 * <br/><b>Fecha | Autor  |  Cambios</b>
 * <ul>
 * <li>Nov 10, 2006 | <a href = "mailto:AngelElectrico@PsiqueWare.com">Angel El&eacute;ctrico</a> | Creaci&oacute;n del Objeto.</li>
 *
 * </ul>
 */

package com.psiqueware.alheli.seguridad;

import com.psiqueware.alheli.dao.EnlaceTransaccional;
import com.psiqueware.alheli.manager.BaseManagerInterface;

/**
 * Encargado de manejar la seguridad de las Credenciales.
 * <br/>Paquete Original: com.psiqueware.basico.seguridad
 * <br/>Nombre  Original: SeguridadUsuariosTManager
 * <br/>Oprima para ver : <a href="UsuariosSeguridadManager.java.html"><i>C&oacute;digo Fuente</i> </a>
 *
 * @author <a href="mailto:AngelElectrico@PsiqueWare.com">Angel El&eacute;ctrico</a>
 * @version Revision: 1.1 Nov 10, 2006 3:49:34 PM
 * @noinspection ClassNamePrefixedWithPackageName
 */
public interface UsuariosSeguridadManager extends BaseManagerInterface
{

    /**
     * {@link Permiso} para hacer operaciones globales. (En oposici&oacute;n a hacer operaciones de {@link Agrupacion}).
     */
    public static Permiso PERMISO = new Permiso("Permiso.SeguridadUsuarios", true);


    /**
     * Devuelve el Nombre del {@link Rol} creado por defecto que contiene los {@link Permiso}s para la administraci&oacute;n de la seguridad.
     * El valor por defecto es "&rtg;U&ltg;". <br/>
     * <b>Importante:</b> Es posible mutar el valor de este {@link Rol} siempre que antes de la creaci&oacute;n de un {@link UsuarioSeguridad} ra&iacute;z
     * se invocara el {@link UsuariosSeguridadManager#setNombreRolUniversal(String)}.
     *
     * @return Valor de 's_nombre_rol_universal'.
     */
    String getNombreRolUniversal();


    /**
     * Establece el Nombre del {@link Rol} creado por defecto que contiene los {@link Permiso}s para la administraci&oacute;n de la seguridad.
     * <b>Importante:</b> Esta operaci&oacute;n debe invocarse antes de la creaci&oacute;n de un {@link UsuarioSeguridad} ra&iacute;z de una {@link Agrupacion} dada.
     * Aunque la implementaci&oacute;n soporta m&uacute;ltiples hilos tambien es de notarse que no se proveen garantias de que un {@link UsuarioSeguridad} ra&iacute;z dado
     * sea invocado con determinado nombre para el rol por defecto.
     *
     * @param nombreRolUniversal Nuevo valor para 's_nombre_rol_universal'.
     */
    void setNombreRolUniversal(final String nombreRolUniversal);

    /**
     * A&ntilde;ade un {@link UsuarioSeguridad} a la lista de control de estos, otorg&aacute;ndole todos los roles.
     * Adem&aacute;s inicializa su credencial, en caso de que no tenga una asignada, le proporciona una con todos los roles.
     *
     * @param usuarioSeguridad    Implementaci&oacute;n de esta interfaz a la que se le asignar&aacute; un usuario de seguridad.
     *                            Debe tener un identificador &uacute;nico, afin de poder distinguir un {@link UsuarioSeguridad} de otro. En caso de no
     *                            estar inicializado este par&aacute;metr&oacute; surgir&aacute; un {@link IllegalArgumentException}.
     * @param enlaceTransaccional enlace para hacer at&oacute;micas las transacciones.
     *
     * @throws SeguridadException en caso de no poder completar la operaci&oacute;n.
     * @noinspection MethodWithMultipleLoops, FeatureEnvy, OverlyLongMethod, CastToConcreteClass
     */
    void registrarUsuarioRaiz(UsuarioSeguridad usuarioSeguridad, final EnlaceTransaccional enlaceTransaccional) throws SeguridadException;

    /**
     * Registra un Usuario en la seguridad.
     *
     * @param usuarioSeguridad    Implementaci&oacute;n de esta interfaz a la que se le asignar&aacute; un usuario de seguridad.
     *                            Debe tener un identificador &uacute;nico, afin de poder distinguir un {@link UsuarioSeguridad} de otro. En caso de no
     *                            estar inicializado este par&aacute;metr&oacute; surgir&aacute; un {@link IllegalArgumentException}.
     * @param enlaceTransaccional enlace para hacer at&oacute;micas las transacciones.
     *
     * @throws SeguridadException           en caso de no poder completar la operaci&oacute;n.
     * @throws UsuarioNoRegistradoException en caso de que el UsuariosSeguridad que se pretende iniciar no se encuentre registrado.
     */
    void iniciarSeguridadUsuario(UsuarioSeguridad usuarioSeguridad, final EnlaceTransaccional enlaceTransaccional) throws SeguridadException, UsuarioNoRegistradoException;

    /**
     * A&ntilde;ade un {@link UsuarioSeguridad} a la lista de control de estos.
     * Adem&aacute;s inicializa su credencial, en caso de que no tenga una asignada, le proporciona una sin roles.
     *
     * @param usuarioSeguridad    Implementaci&oacute;n de esta interfaz a la que se le asignar&aacute; un usuario de seguridad.
     *                            Debe tener un identificador &uacute;nico, afin de poder distinguir un {@link UsuarioSeguridad} de otro. En caso de no
     *                            estar inicializado este par&aacute;metr&oacute; surgir&aacute; un {@link IllegalArgumentException}.
     * @param autoriza            {@link UsuarioSeguridad} que tiene los {@link Permiso}s para validar la operaci&oacute;n.
     * @param enlaceTransaccional enlace para hacer at&oacute;micas las transacciones.
     *
     * @throws SeguridadException en caso de no poder completar la operaci&oacute;n.
     * @noinspection FeatureEnvy, CastToConcreteClass
     */
    void registrarNuevoUsuario(UsuarioSeguridad usuarioSeguridad, UsuarioSeguridad autoriza, final EnlaceTransaccional enlaceTransaccional) throws SeguridadException;

    /**
     * Elimina un {@link UsuarioSeguridad} de la aplicaci&oacute;n.
     * <br/><b>Consideraciones</b>
     * <br/> Se pueden dar 2 casos:
     * <ul>
     * <li>Se pretende eliminar un usuario normal.- Se elimina la credencial de dicho usuario.</li>
     * <li>Se pretende eliminar un super usuario .- Se elimina la credencial de dicho usuario, el agrupacion, todos los roles y credenciales dados de alta para dicho agrupacion.</li>
     * </ul>
     * Si ya no hay id registrados para el {@link Agrupacion} del {@link UsuarioSeguridad}
     * elimina tambien el {@link Agrupacion} y sus respectivos {@link Rol}es.
     *
     * @param enlaceTransaccional enlace para hacer at&oacute;micas las transacciones.
     * @param eliminar            {@link UsuarioSeguridad} a eliminar.
     * @param autoriza            {@link UsuarioSeguridad} que autoriza la transacci&oacute;n.
     *
     * @return <code>true</code> si se elimin&oacute; sin problemas; <code>false</code> en caso contrario.
     *
     * @throws com.psiqueware.alheli.seguridad.SeguridadException en caso de que el {@link UsuarioSeguridad} no se eliminara correctamente.
     * @noinspection MethodWithMultipleLoops, FeatureEnvy
     */
    boolean removeUsuario(UsuarioSeguridad eliminar, UsuarioSeguridad autoriza, final EnlaceTransaccional enlaceTransaccional) throws SeguridadException;
}
